Write a Modal Test with Cypress

We’ve had some practice with the Cypress API through writing page-level tests and simple interactions at the component level.

It’s time to take it up a notch and start writing tests that mimic more complex interactions than just a single keypress or click.

Cypress shines when it comes to writing integration tests that more closely imitate how an actual user would interact with a site. It allows for testing navigation and other scenarios to identify issues that tools alone might not be able to catch.

There are plenty of opportunities to write these tests for the CampSpots Passes page.

The Passes page features two pricing cards with “Join Now” buttons that open a modal with a payment form.

In this lesson, we’ll be adding some tests to PassesPage.test.js inside of the exercise3-cypress-integration directory.

🛠 Challenge: Write a Test for Payment Dialog Focus Management

When focus management is done correctly, a user who opens a modal or other interactive component will be taken back to the element they started from when closing out of it.

When the user clicks a “Join Now” button on the pricing page a modal opens. Closing out of the modal should put focus back on the button that opened it.

Your challenge is to write a test that ensures that the payment dialog is accessible.

Your test should interact with a button to open the modal, then ensure that it has focus.

Cypress should then be able to tab to the close button, and when the dialog is closed the button that opened it should have focus.

It’s okay to write a failing test— the important thing is that you capture the steps for the focus management behavior.

Refer back to previous Cypress & Cypress Component Testing exercises, or look in the answer directory if you get stuck.

🛠 Solution Part 1: Writing a Focus Management Test for the Dialog

There are multiple ways to write this test— this is just my approach!

Inside of PassesPage.test.js I’ll add a new it() block with a description of “should have an accessible payment dialog” along with an arrow function:

it('should have an accessible payment dialog', () => {

})

it('should have an accessible payment dialog', () => {

})

Inside the test block I’ll use cy.get() along with the id selector for the Basic “Join Now” button then chain on .focus() and .click() to open the modal.

With the dialog open, I’ll use cy.focused() to check that the focused element has an ARIA role of dialog.

Next, I’ll use cy.realPress() to simulate pressing the Tab key which should give focus to the close button. I’ll assert that the focused element should have an aria-label of “Close Dialog”.

Instead of hitting enter with focus on the close button, I’ll change it up and send an Escape key event. This should close the dialog from wherever the focus is inside of it.

Finally, to check if focus is back at the Basic “Join Now” button, I’ll use cy.focused() and assert the element has the id.

Here’s what my test looks like all together:

it('should have an accessible payment dialog', () => {
        cy.get('#btn-join-basic').focus().click()

        // focus is sent into dialog
        cy.focused().should('have.attr', 'role', 'dialog')

        cy.realPress(["Tab"])
        cy.focused().should('have.attr', 'aria-label', 'Close Dialog')

        cy.realPress(["Escape"])
        cy.focused().should('have.attr', 'id', 'btn-join-basic')
    })

it('should have an accessible payment dialog', () => {
        cy.get('#btn-join-basic').focus().click()

        // focus is sent into dialog
        cy.focused().should('have.attr', 'role', 'dialog')

        cy.realPress(["Tab"])
        cy.focused().should('have.attr', 'aria-label', 'Close Dialog')

        cy.realPress(["Escape"])
        cy.focused().should('have.attr', 'id', 'btn-join-basic')
    })

Analyzing Test Results

Cypress was about to find the button, and click it to open the dialog. But once the dialog was open, it couldn’t find the “Close Dialog” aria-label.

This is an example of aria-label being a brittle thing to base a test on. We know the the button is getting focused— but the missing attribute makes the test fail.

Using a data-testid attribute might provide a good alternative for many tests. However, in this case I’ll stick with aria-label because the button’s text is only an “X” which isn’t as informative for screen readers as it could be.

🛠 Solution Part 2: Running the Test and Fixing Issues

Add an ARIA Label to the Close Button

The code for the close button is inside the Dialog subcomponent inside of page-passes.js.

Adding an aria-label of “Close dialog” will take care of the first issue we have:

// inside page-passes.js

<header>
	<button
		aria-label="Close dialog"
		className="btn-close-dialog"
		...

// inside page-passes.js

<header>
	<button
		aria-label="Close dialog"
		className="btn-close-dialog"
		...

Now when we re-run the test, it fails because the Escape key doesn’t close the modal dialog so focus is still on the close button instead of back on the join button.

Implement an Escape Key Handler

On the subscription details div that surrounds the payment dialog, we’ll add an onKeyUp

handler. We’ll pass the event into a new handler function we’ll write called handleDialogEscape:

<div
	aria-label="Subscription details"
	onKeyUp={(event) => handleDialogEscape(event)}
	...

<div
	aria-label="Subscription details"
	onKeyUp={(event) => handleDialogEscape(event)}
	...

Then near the top of our component above the return, we’ll write the handleDialogEscape function.

It will take in the event, then inside we’ll add an if statement to check if event.key is the Escape key. It if is, we’ll close the dialog the same was as clicking the button would.

Here’s the the Escape key handler looks like:

const handleDialogEscape = (event) => {
	if (event.key === 'Escape') {
		setDialogState(false)
		appContext.setInertMarkupValue(false)
	}
}

const handleDialogEscape = (event) => {
	if (event.key === 'Escape') {
		setDialogState(false)
		appContext.setInertMarkupValue(false)
	}
}

Saving our work and re-running the tests, everything passes as expected!

The Focus Management Concern of Layers

When the modal dialog is closed, all of the regular content on the page is focusable.

If the modal is open, we don’t want the user to be stuck in the header or anywhere else behind the dialog.

To accomplish this, the dialog is rendered inside of the HeaderPortal component inside of passes-page.js. Recall that this moves it above all of the other content on the page.

When the dialog is open, the inert attribute is added to the header, main, and footer elements. This adds an aria-hidden of true and prevents the user from being able to access any of the elements behind the dialog. And just to make extra sure, these elements also have set a tabindex of -1 set which prevents them from being reached with the tab key.

Testing tab key behavior can be tricking in Cypress.

This is kind of a tricky thing to test in Cypress. Because Cypress uses an actual browser instance, if you send Tab key events after the last element in the dialog, you will end up in the browser’s toolbar.

Adding a focus trap to the page where the tab key continuously cycles through the elements might be one solution for when the dialog is open.